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Preface 


This document contains the information that you need to administer the IBM® 
Tivoli® Directory Server. 


Who should read this book 

This book is intended for System administrators. 


Publications 


Read the descriptions of the IBM Tivoli Directory Server library to determine 
which publications you might find helpful. After you determine the publications 
you need, refer to the instructions for accessing publications online. 


IBM Tivoli Directory Server library 

The publications in the IBM Tivoli Directory Server library are: 

IBM Tivoli Directo n/ Server Version 5.2 Read me Addendum 

Go to the Tivoli Software Library Web site to access the Readme 
Addendum for IBM Tivoli Directory Server 5.2, which cont ains importa nt 


information that was not includ ed in the Readme files. See |" Accessing 


publications online" on page vi| for information about accessing online 


publications. 

IBM Tivoli Directory Server Version 5.2 Client Readme 

Contains information last-minute information about the dient. 

IBM Tivoli Directory Server Version 5.2 Server Readme 

Contains last-minute information about the Server. 


IBM Tivoli Directory Server Version 5.2 Web Administration Tool Readme 

Contains last-minute information about the Web Administration Tool. This 
Readme is available from the main panel of the Web Administration Tool. 

IBM Tivoli Directory Server Version 5.2 Installation and Configuration Guide 

Contains complete information for installing the IBM Tivoli Directory 
Server dient, Server, and Web Administration Tool. Includes information 
about migrating from a previous version of IBM Tivoli Directory Server or 
SecureWay® Directory. 

IBM Tivoli Directory Server Version 5.2 Tuning Guide 

Contains information about tuning your Server for better performance. 

IBM Tivoli Directory Server Version 5.2 Administration Guide 

Contains instructions for performing administrator tasks through the Web 
Administration Tool or the command line. 

IBM Tivoli Directory Server Version 5.2 Plug-in Reference 

Contains information about writing Server plug-ins. 

IBM Tivoli Directory Server Version 5.2 C-Client SDK Programming Reference 
Contains information about writing LDAP dient applications. 
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Related publications 


Information related to the IBM Tivoli Directory Server is available in the following 
publications: 


• The IBM Tivoli Directory Server Version 5.2 uses the JNDI dient from Sun 
Microsystems. For information about the JNDI dient, refer to the Java™ Naming 
and Directory Interface™ 1.2.1 Syecification on the Sun Microsys tems Web site at 
http://java.sun.com/products/jndi/1.2/javadoc/index.html . 


• The Tivoli Software Library provides a variety of Tivoli publications such as 
white papers, datasheets, demonstrations, redbooks, and announcement letters. 
The Tivoli Software Library is available on the W eb at: 
http: / / www. ibm. com / Software / tivoli / library / 


The Tivoli Software Glossary includes definitions for many of the technical terms 
related to Tivoli Software. The Tivoli Software Glossary is available, in English 
only, from the Glossary link on the left side of the Tiv oli Software Library Web 


page http://www.ibm.com/software/tivoli/library/ 


Accessing publications online 


The publications for this product are available online in Portable Document Format 
(PDF) or Hypert ext Markup Language (HTML) format, or both in the Tivoli 
Software library: http://www.ibm.com/software/tivoli/library 


To locate product publications in the library, dick the Product manuals link on the 
left side of the Library page. Then, locate and dick the name of the product on the 
Tivoli Software information center page. 


Information is organized by product and includes READMEs, installation guides, 
user's guides, administrator's guides, and developer's references. 


Note: To ensure proper printing of PDF publications, select the Fit to page check 
box in the Adobe Acrobat Print window (which is available when you dick 

File ■* Print). 


Accessibility 

Accessibility features help a user who has a physical disability, such as restricted 
mobility or limited vision, to use Software products successfully. With this product, 
you can use assistive technologies to hear and navigate the interface. After 
installation you also can use the keyboard instead of the mouse to operate all 
features of the graphical user interface. 


Contacting Software Support 

Betöre contacting IBM Tivoli Software support with a problem, refer to IBM System 
Management and Tivoli Software Web site at: 


http://www.ibm.com/software/sysmgmt/products/support/ 


If you need additional help, contact Software support by using the methods 
described in the IBM Software Support Guide at the following Web site: 


http://techsupport.services.ibm.com/guides/handbook.html 


The guide provides the following information: 

• Registration and eligibility requirements for receiving support 
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• Telephone numbers and e-mail addresses, depending on the country in which 
you are located 

• A list of information you should gather before contacting customer support 


Conventions used in this book 

This reference uses several conventions for special terms and actions and for 

operating system-dependent commands and paths. 

Typeface conventions 

The following typeface conventions are used in this reference: 

Bold Lowercase commands or mixed case commands that are difficult to 

distinguish from surrounding text, keywords, parameters, options, names 
of Java classes, and objects are in bold. 

Italic Titles of publications, and special words or phrases that are emphasized 
are in italic. 


<Italic> 

Variables are set off with < > and are in <italic>. 

Monospace 

Code examples, command lines, screen output, file and directory names 
that are difficult to distinguish from surrounding text, System messages, 
text that the user must type, and values for arguments or command 
options are in monospace. 

Operating System differences 

This book uses the UNIX® convention for specifying environment variables and for 
directory notation. When using the Windows® command line, replace $variable 
with %variable% for environment variables and replace each forward slash (/) with 
a backslash (\) in directory paths. If you are using the bash shell on a Windows 
System, you can use the UNIX conventions. 
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Chapter 1. Introduction to Server plug-ins 


Use the IBM Tivoli Directory Server Plug-ins Reference to help you create plug-ins 
that extend the capabilities of your IBM Tivoli Directory Server. 

Server plug-ins extend the capabilities of your Directory Server. They are 
dynamically loaded into the LDAP server's address space when it is started. Once 
the plug-ins are loaded, the Server calls the functions in a shared library by using 
function pointers. 

A Server front-end listens to the wire, receives and parses requests from clients, 
and then processes the requests by calling an appropriate database back-end 
function. 

A Server back-end reads and writes data to the database containing the directory 
entries. In addition to the default database operations, the LDAP Server Database 2 
(DB2®) back-end also provides functions for supporting replication and dynamic 
Schema Updates. 

If the front-end fails to process a request it returns an error message to the dient; 
otherwise, the back-end is called. After the back-end is called, it must return a 
message to the dient. Either the front-end or the back-end, but not both can return 
a message to the dient. 

Note: This differs from the iPlanet Server plug-in in that only the front-end of the 
iPlanet plug-in can send a message back to the dient. 

In this release of the IBM Tivoli Directory Server the following types of Server 
plug-ins are supported: 

Database plug-ins 

Can be used to integrate your own database as a back-end to the Server. A 
database plug-in can consist of all or only a portion of the functions 
discussed in this document. For example, the rdbm database back-end is a 
database plug-in. It provides functions that enable the Server to interact 
with the DB2 database. 

Pre-operation plug-ins 

Functions that are executed betöre an LDAP Operation is performed. For 
example, you can write a plug-in that checks new entries betöre they are 
added to the directory. 

Post-operation plug-ins 

Functions that are executed after an LDAP Operation is performed. 

Extended Operation plug-ins 

Are used to handle extended operations protocol that are defined in the 
LDAP V3 protocol. 

Audit plug-ins 

Are used to improve the security of the directory Server. A default audit 
plug-in is provided with the Server. Depending on the audit configuration 
parameters, this plug-in might log an audit entry in the default or specified 
audit log for each LDAP Operation the Server processed. The IBM Tivoli 
Directory Server administrator can use the activities stored in the audit log 
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to check for suspicious pattems of activity in an attempt to detect security 
violations. If security is violated, the audit log can be used to determine 
how and when the problem occurred and perhaps the amount of damage 
done. This information is very useful, both for recovery from the violation 
and, possibly, in the development of better security measures to prevent 
future problems. You can also write your own audit plug-ins to either 
replace, or add more processing to, the default audit plug-in. 

A Server plug-in can return a message to the dient as well. However, make sure 

that the Server returns only one message. 
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Chapter 2. Writing a plug-in 


A pblock is an opaque structure in which many parameters are stored. It is used to 

communicate between the Server and your plug-ins. Application program 

interfaces (APIs) are provided for your plug-ins to get (or set) parameters in this 

structure. 

Notes: 

1. Plug-ins must be written using reentrant System calls. 

2. There is no global mutex issue that the plug-in writer has to be concerned 
about in terms of interacting with the Server. As long as the plug-ins call 
server-provided slapi APIs, a server's shared resource is protected by the APIs. 
However, because each request is serviced by a thread, and each thread might 
exercise the plug-in code, if there is any shared resource that the plug-in code 
creates, then mutex might be needed to protect the resources. 

The following are examples of supported Compilers: 

• For Windows platforms—MS Visual C++ 6.0 and IBM VisualAge® C++ 3.5 

• For AIX® platforms—IBM VisualAge C++ 5.0.x 

• For Linux platforms—GCS 3.2 

• For Solaris platforms—IBM CSet++ 1.1 WorkShop Pro 6 update 1 

• For HP platforms—aCC A.03.25 


To write your own plug-in: 

1. Start by writing your functions. Include slapi-plugin.h (where you can find all 
the parameters that can be defined in the pblock). You also can find a set of 
function prototypes for the available functions in the slapi-plugin.h file. 


2 . 


Decide the input parameters for your functions. Depending on the type of 
plug-in you are writing, you might need to work with a different set of 
parameters. See Appendix A, "Supported database functions", on page 13 for 
more Information. 


3. The following output is received from your functions: 


return code 

You can have the return code set to 0, which means that the Server 
continues the Operation. A return code of non-zero means that the 
Server stops processing the Operation. For example, if you have a 
pre-operation bind function that authenticates a user, it retums a 
non-zero after the authentication has been completed successfully. 
Otherwise, you can return a 0 and let the default bind Operation 
continue the authentication process. 

return a message to the dient 

You might want your plug-in (a pre-operation, a database Operation, or 
a post-operation) to send an LDAP result to the dient. For each 
Operation, make sure there is only one LDAP result sent. 


Note: The IBM Tivoli Directory Server default database plug-in always 
sends back a message. If you use the default database, do not 
have the post-operation return a message to the dient. 
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4. 

5. 


output parameter 

You might want to update parameters in the pblock that were passed 
to your function. For example, after your pre-operation bind function 
authenticates a user, you might want your plug-in to return the bound 
user's DN to the Server. The Server can then use it to contue to pr ocess 


the operations rquested by the u ser. See Appendix A, "Supported 


database functions", on page 13 for possible output parameters. 


Call slapi APIs in the libslapi library file. See Appendix B, "Supported iPlanet 


APIs", on page 15 for Information about the APIs supported in this release. 


Write an initialization function for your plug-in to register your plug-in 
functions. 


6. Export your initialization function from your plug-in shared library. Use an 
.exp file for AIX or a .def (or dllexport) file for Windows NT® to export your 
initialization. For other UNIX platforms, the exportation of the function is 
automatic when you create the shared library. 

7. Compile and link your Server plug-in object files with whatever libraries you 
need, and libslapi library file. 

8. Add a plug-in directive in the Server configuration file. The syntax of the 
plug-in directive is: 

attributeName: plugin-type plugin-path init-func args ... 

9. On a Windows NT operating System, in the ibmslapd.conf file, the plug-in 
directive is as follows: 


dn: cn=Directory, cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration 
ibm-slapdPlugin: database /Iib/1ibldap-2dbm.dl1 rdbm_backend_init 


Note: For the AIX, Linux, Solaris and HP operating platforms, the .dll 
extension is replaced with the appropriate extension: 

• For AIX and Linux operating Systems - .a 

• For Solaris operating Systems - .so 

• For HP-UX operating Systems - .sl 


The following rules apply when you place a plug-in directive in the configuration 
file: 

• Multiple pre- or post-operations are called in the Order they appear in the 
configuration file. 

• The Server can pass parameters to your plug-in initialization function by way of 
the argument list that is specified in the plug-in directive. 

ibm-slapdPlugin is the attribute used to specify a plug-in which can be loaded by 
the Server. This attribute is one of the attributes contained in objectclasses, such as 
ibm-slapdRdbmBackend and ibm-slapdLdcfBackend. For instance, in 
ibmslapd.conf, there is an entry which identifies the rdbm backend. In this entry, a 
database plug-in is specified by using the ibm-slapdPlugin attribute so that the 
Server knows where and how to load this plug-in. If there is another plug-in to be 
loaded, such as a changelog plug-in, then specify it using another ibm-slapdPlugin 
attribute. 

dn: cn=Directory,cn=RDBM Backends,cn=IBM SecureWay,cn=Schemas,cn=Configuration 
objectclass: ibm-slapdRdbmBackend 

ibm-slapdPlugin: database libback-rdbm.dll rdbm_backend_init 
ibm-slapdPlugin: preoperation 1 ibei .dll CLInit "cn=changelog" 
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Chapter 3. Database plug-ins 

Database plug-ins can be used to integrate your own database as a back-end to the 
Server. A database plug-in can consist of all or a portion of the functions discussed 
in this section. 

LDAP protocol-related functions 

Are the default database functions. When you write a database plug-in you 
might not want to provide every function to handle the default database 
operations. You might need to provide some stub functions, however, 
which are used to send back an unwi 11 i ng to perform message to the 
dient when a particular function is not active. 

Back-end-related functions 

Are used to initialize or shut down the back-end and to handle 
back-end-specific configuration. 


LDAP protocol-related functions 

The following LDAP protocol-related functions are also the default database 
functions: 

SLAPI_PLUGIN_DB_BIND_FN 

Allows authentication information to be exchanged between the dient and 
Server. 

SLAPI_PLUGIN_DB_UNBIND_FN 

Terminates a protocol Session. 

SLAPI_PLUGIN_DB_ADD_FN 

Adds an entry to the directory. 

SLAPI_PLUGIN_DB_DELETE_FN 

Deletes an entry. 

SLAPI_PLUGIN_DB_SEARCH_FN 

An LDAP back-end search routine. 

SLAPI_PLUGIN_DB_COMPARE_FN 

Gets the entry DN information and compares it with the attributes and 
values used in the compare function. 

SLAPI_PLUGIN_DB_MODIFY_FN 

Modifies an entry. 

SLAPI_PLUGIN_DB_MODRDN_FN 

Changes the last component of the name of an entry. 


Back-end-related functions 

These database back-end-related functions are used to initialize or shut down the 
back-end and to handle back-end-specific configuration: 

SLAPI_PLUGIN_DB_INIT_FN 

An LDAP back-end initialization routine. 

SLAPI_PLUGIN_CLOSE_FN 

An LDAP back-end close routine. 
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Note: Stand-alone, user-supplied Server back-end plug-ins are not supported. 
However, they are supported when used in parallel with IBM-supplied 
Server back-end plug-ins. 
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Chapter 4. Operation plug-ins 

The following plug-in functions can be performed before or after an LDAP 
Operation. 


Pre-operation plug-ins 

The following pre-operation functions can be executed before an LDAP Operation 
is performed: 

SLAPI_PLUGIN_PRE_BIND_FN 

A function to call before the Directory Server executes an LDAP bind 
Operation. 

SLAPI_PLUGIN_PRE_UNBIND_FN 

A function to call before the Directory Server executes an LDAP unbind 
Operation. 

SLAPI_PLUGIN_PRE_ADD_FN 

A function to call before the Directory Server executes an LDAP add 
Operation. 

SLAPI_PLUGIN_PRE_DELETE_FN 

A function to call before the Directory Server executes an LDAP delete 
Operation. 

SLAPI_PLUGIN_PRE_SFARCH_FN 

A function to call before the Directory Server executes an LDAP search 
Operation. 

SLAPI_PLUGIN_PRE_COMPARE_FN 

A function to call before the Directory Server executes an LDAP compare 
Operation. 

SLAPI_PLUGIN_PRE_MODIFY_FN 

A function to call before the Directory Server executes an LDAP modify 
Operation. 

SLAPI_PLUGIN_PRE_MODRDN_FN 

A function to call before the Directory Server executes a modify RDN 
database Operation. 


Post-operation plug-ins 

The following post-operation plug-in functions can be executed after an LDAP 
Operation is performed: 

SLAPI_PLUGIN_POST_BIND_FN 

A function to call after the Directory Server executes an LDAP bind 
Operation. 

SLAPI_PLUGIN_POST_UNBIND_FN 

A function to call after the Directory Server executes an LDAP unbind 
Operation. 

SLAPI_PLUGIN_POST_ADD_FN 

A function to call after the Directory Server executes an LDAP add 
Operation. 
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SLAPI_PLUGIN_POST_DELETE_FN 

A function to call after the Directory Server executes an LDAP delete 
Operation. 

SLAPI_PLUGIN_POST_SEARCH_FN 

A function to call after the Directory Server executes an LDAP search 
Operation. 

SLAPI_PLUGIN_POST_COMPARE_FN 

A function to call after the Directory Server executes an LDAP compare 
Operation. 

SLAPI_PLUGIN_POST_MODIFY_FN 

A function to call after the Directory Server executes an LDAP modify 
Operation. 

SLAPI_PLUGIN_POST_MODRDN_FN 

A function to call after the Directory Server executes an LDAP modify 
RDN database Operation. 


Extended Operation plug-ins 

LDAP operations can be extended with your own extended Operation functions 
provided by a plug-in. An extended Operation function might have an interface 
such as: 

int myExtendedOp(Slapi_PBl ock *pb); 

In this function, you can obtain the following two input parameters from the 
pblock passed in and communicate back to the Server front-end with the following 
two output parameters: 

Input parameters 

These parameters can be obtained by calling the slapi_pblock_get API. 

SLAPI_EXT_OP_RET_OID (char *) 

The object identifier specified in a client's request. 

SLAPI_EXT_OP_REQ_VALUE (struct berval *) 

The Information in a form defined by that request. 

Output parameters 

These parameters can be put to the parameter block passed in by the Server by 
calling the slapi_pblock_set API. 

SLAPI_EXT_OP_RET_OID (char *) 

The object identifier that the plug-in function wants to send back to the 
dient. 

SLAPI_EXT_OP_RET_VALUE (struct berval *) 

The value that the plug-in function wants to send back to the dient. 

After receiving and processing an extended Operation request, an extended 
Operation plug-in function might itself send an extended Operation response back 
to a dient or let the Server send such a response. If the plug-in decides to send a 
response, it might call the slapi_send_ldap_result() function and return a result 
code SLAPI_PLUGIN_EXTENDED_SEND_RESULT to the Server indicating that the 
plug-in has already sent an LDAP result message to the dient. If the plug-in has 
not sent an LDAP result message to the dient, the plug-in returns an LDAP result 
code and the Server sends this result code back to the dient. 
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To register an extended Operation function, the initialization function of the 
extended Operation plug-in might call slapi_pblock_set() to set the 
SLAPI_PLUGIN_EXT_OP_FN to the extended Operation function and the 
SLAPI_PLUGIN_EXT_OP_OIDLIST parameter to the list of extended Operation 
OIDs supported by the function. The list of OIDs which is listed in the 
ibm-slapdPlugin directive in ibmslapd.conf can be obtained by getting the 
SLAPI_PLUGIN_ARGV parameter from the pblock passed in. 

The Server keeps a list of all the OIDs that are set by plug-ins using the parameter 
SLAPI_PLUGIN_EXT_OP_OIDLIST. This list of extended operations can be queried 
by performing a search of the root DSE. 

For example, in the Windows NT environment to specify an extended Operation 
plug-in in the ibmslapd.conf file for the database rdbm add the following: 

dn: cn=Directory, cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration 
ibm-slapdPlugin database /bin/1ibback-rdbm.dl1 rdbm_backend_init 
ibm-slapdPlugin extendedop /tmp/myextop.dl1 myExtendedOpInit 123.456.789 

File paths starting with a forward slash ( / ) are relative to the LDAP install 
directory; /tmp is changed to <ldap>\tmp, but C:\tmp is unchanged. This 
indicates that the function myExtendedOpInit that can be found in the 
/path/ myextop.dll shared library is executed when the Server starts. The 
myExtendedOp function that is registered in the initialization is used to handle the 
extended-operations. This function handles extended operations with the Object 
Identifier (OID) 123.456.789. 

Note: For the AIX, Linux, Solaris and HP operating platforms, the .dll extension is 
replaced with the appropriate extension: 

• For AIX and Linux operating Systems - .a 

• For Solaris operating Systems - .so 

• For HP-UX operating Systems - .sl 

Remember that plug-in directives are per-database. 


Audit plug-ins 

The Administrators of some platforms might want to use the System audit facilities 
to log the LDAP audit record with the system-defined record format. To allow 
flexibility in logging and record formats, a plug-in interface is provided. The Server 
uses this interface to provide three types of auditing-related data to the external 
audit plug-ins if the auditing configuration is set to on. The data is passed to the 
external audit plug-ins through the Standard plug-in's pblock interfaces, 
slapi_pblock_set() and slapi_pblock_get(). 

The three types of audit data available to the external audit plug-ins are: 

Audit Configuration Information 

This information is used to inform the external audit plug-in that at least 
one of the audit configuration options has been changed. The Server 
expects the plug-in to determine whether to log the audit data associated 
with a particular LDAP Operation, so it is important for the plug-in to have 
the current audit configuration information maintained by the Server. 

Audit Event Information 

This information is used to inform the audit plug-in that certain events 
have happened. Event IDs, such as Auditing Started, Auditing Ended, or 
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Audit Configuration Options Changed, along with a message text 
describing the event, are sent by the Server to the audit plug-in when such 
events occur. 

Audit Record Information 

This Information is the audit data associated with each LDAP request 
received by the Server. For each LDAP request, if the ibm-audit 
configuration Option is set, the Server provides the header data, control 
structure (if available), and operation-specific data to the audit plug-in. It is 
up to the audit plug-in to check its own copy of the LDAP audit 
configuration options or its platform-specific audit policy to determine 
whether to log and how to log the audit data. 

The header file, audit-plugin.h, that defines the audit plug-in interface and data 
structures is shipped with the IBM Tivoli Directory Server C-Client SDK. 

A default audit plug-in is provided and configured with the Server. This plug-in 
performs the logging and formatting of the LDAP audit record. This default 
plug-in can be replaced with the platform-specific audit plug-in, if available, by 
changing the plug-in configuration lines in the ibmslapd.conf configuration file or 
through the IBM Tivoli Directory Server Administration. 

Configuration options 

The Audit Service has the following configuration options: 

ibm-auditLog 

Specifies the path name of the audit log. The default is /var/ldap/audit 
for Unix platforms and <LDAP instnll directory> \ va r \a u d i t for the NT 
platform. 

ibm-audit: TRUE IFALSE 

Enables or disables the audit Service. Default is FALSE. 

ibm-auditFailedOPonly: TRUE I FALSE 

Indicates whether to log only failed operations. Default is TRUE. 

ibm-auditBind: TRUE I FALSE 

Indicates whether to log the Bind Operation. Default is TRUE. 

ibm-auditUnbind: TRUE I FALSE 

Indicates whether to log the Unbind Operation. Default is TRUE. 

ibm-auditSearch: TRUE I FALSE 

Indicates whether to log the Search Operation. Default is FALSE. 

ibm-auditAdd: TRUE I FALSE 

Indicates whether to log the Add Operation. Default is FALSE. 

ibm-auditModify: TRUE I FALSE 

Indicates whether to log the Modify Operation. Default is FALSE. 

ibm-auditDelete: TRUE I FALSE 

Indicates whether to log the Delete Operation. Default is FALSE. 

ibm-auditModifyDN: TRUE I FALSE 

Indicates whether to log the ModifyRDN Operation. Default is FALSE. 

ibm-auditExtOPEvent: TRUE I FALSE 

Indicates whether to log LDAP V3 Event Notification extended operations. 
Default is FALSE. 
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These options are stored in the LDAP directory to allow dynamic configuration. A 
directory entry, cn=audit, cn=localhost, is created to contain these options. The 
access to the values of these options are controlled through the access control list 
(ACL) model. By default, the LDAP administrator is the owner of this cn=audit 
entry However, with the current ACL functionality, an auditor role can be created 
so that only the auditor can change the Option values and location of the audit log. 

Note: For each modification of these Option values, a message is logged in the 
slapd error log as well as the audit log to indicate the change. 

The values of the audit configuration options are retumed when a search of 
cn=monitor is requested by the LDAP administrator. These include: 

• The value of the audit configuration options. 

• The number of audit entries sent to the Audit plug-in for the current auditing 
session and for the current Server session. 

Examples 

The following are examples of the various operations: 

2001-07-24-15:01:01.345-06:00—V3 Bind— 

bindDN:cn=test—dient: 9.1.2.3:12345—Connection ID: 12— 
received: 2001-07-24-15:01:01.330-06:00—adminAuthority:Y—success 
name: cn=test 

authenticationChoice: simple 


2001-07-24-15:01:02.367-06:00--V3 Search- 

bi ndDN: cn=test—cl ient :9.1.2.3:12345—ConnectionID: 12— 
received:2001-07-24-15:01:02.360-06:00--adminAuthority:Y--success 
base: o=ibm_us,c=us 
scope: wholeSubtree 
derefAliases: neverDerefAliases 
typesOnly: false 
filter: (&(cn=c*)(sn=a*)) 

Note: See the following examples for the format differences between authenticated 
and unauthenticated requests: 

2001-07-24-15:22:33.541-06:00—V3 unauthenticated Search-- 

bi ndDN: <*CN=NULLDN*>—client:9.1.2.2:32412—ConnectionID:18— 
received:2001-07-24-15:22:33.539-06:00—adminAuthority:Y—success 


2001-07-24-15:22:34.555-06:00--V3 SSL unauthenticated Search-- 
bi ndDN: <*CN=NULLDN*>—dient :9.1.2.2:32412—ConnectionID: 19— 
received:2OOl-O7-24-15:22:34.55O-06:OO—adminAuthority:Y—success 


2001-07-24-15:01:03.123-06:0O--V3 Add— 

bindDN:cn=test—dient: 9.1.2.3:12345—Connection ID: 12— 
received: 2001-07-24-15:01:03.100-06:00—adminAuthority:Y--entryAlreadyExists 
entry: cn=Jim Brown, ou=sales,o=ibm_us,c=us 
attributes: objectclass, cn, sn, telphonenumber 


2001-07-24-15:01:04.378-06:00—V3 Delete— 

bindDN:cn=test—dient: 9.1.2.3:12345—Connection ID: 12— 
received: 2001-07-24-15:01:04.370-06:00—adminAuthority:Y—success 
entry: cn=Jim Brown, ou=sales,o=ibm_us,c=us 


2001-07-24-15:01:05.712-06:0O--V3 Modify— 

bindDN:cn=test—dient: 9.1.2.3:12345—Connection ID: 12— 
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received:2001-07-24-15:01:05.708-06:00--adminAuthority:Y--noSuchObject 
object: cn=Jim Brown, ou=sales,o=ibm_us,c=us 
add: mail 

delete: telephonenumber 


2001-07-24-15:01:06.534-06:00—V3 ModifyDN— 

bindDN:cn=test—cl ient:9.1.2.3:12345—ConnectionID:12— 
received:2001-07-24-15:01:06.530-06:QO--adminAuthority:Y--noSuchObject 
entry: cn=Jim Brown, ou=sales,o=ibm_us,c=us 
newrdn: ou=r&d 
deleteoldrdn: true 


2001-07-24-15:01:07.913-06:00—V3 Unbind— 

bindDN:cn=test—cl ient:9.1.2.3:12345—ConnectionID: 12— 

recei ved: 2001-07-24-15:01:07.910-06:00—adminAuthority:Y—success 
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Appendix A. Supported database functions 


The three parameters in the first stanza are passed to the nine default database 
functions as input: 

/* backend, connection, Operation */ 

SLAPI_BACKEND 
S LAPI_C0NNECTION 
SLAPI_OPERATION 

/* arguments that are common to all operations */ 

SLAPI_CONN_DN 

SLAPI_CONN_AUTHTYPE 

SLAPI_REQCONTROLS 

/* add arguments */ 

SLAPI_ADD_TARGET 

SLAPI_ADD_ENTRY 

/* bind arguments */ 

SLAPI_BIND_TARGET 
S LAPI_BIND_METH0D 
S LAPI_BIND_CREDENTIALS 
SLAPI_BIND_SASLMECHANISM 
/* bind return values */ 

S LAPI_BIND_RET_SAS LCREDS 

/* compare arguments */ 

SLAPI_COMPARE_TARGET 

SLAPI_COMPARE_TYPE 

SLAPI_COMPARE_VALUE 

/* delete arguments */ 

SLAPI_DELETE_TARGET 

/* modify arguments 


Note: The input and output value for setting and getting SLAPI_MODIFY_MODS 
in the slapi_pblock_set() and slapi_pblock_get() functions is a pointer to a 
list of LDAPMod structures. This differs from the iPlanet implementation 
which is a pointer to an array of LDAPMod pointers. Go to the LDAPMod 
structure in the ldap.h file to see how to traverse the linked list using the 
pointer to the next LDAPMod structure. 

*/ 

SLAPI_MODIFY_TARGET 

SLAPI_MODIFY_MODS 

/* modrdn arguments */ 

SLAPI_MODRDN_TARGET 

SLAPI_MODRDN_NEWRDN 

SLAPI_MODRDN_DELOLDRDN 

SLAPI_MODRDN_NEWSUPERIOR 

/* search arguments */ 

SLAPI_SEARCH_TARGET 
SLAPI_SEARCH_SCOPE 
SLAPI_SEARCH_DEREF 
S LAPI_S EARCH_SIZELIMIT 
SLAPI_SEARCH_TIMELIMIT 
SLAPI_SEARCH_FILTER 
SLAPI SEARCH STRFILTER 
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SLAPI_SEARCH_ATTRS 

SLAPI_SEARCH_ATTRSONLY 

/* abandon arguments */ 
SLAPI_ABANDON_MSGID 

/* plugin types supported */ 
fdefine SLAPI_PLUGIN_DATABASE 
Idefine SLAPI_PLUGIN_EXTENDEDOP 
#define SLAPI_PLUGIN_PREOPERATION 
#define SLAPI_PLUGIN_POSTOPERATION 
fdefine SLAPI_PLUGIN_AUDIT 

/* plugin configuration pararrs */ 
Idefine SLAPI_PLUGIN 
fdefine SLAPI_PLUG IN_PRIVATE 
fdefine SLAPI_PLUGIN_TYPE 
fdefine SLAPI_PLUGIN_ARGV 
Idefine SLAPI_PLUG IN_ARGC 

/* audit plugin defines */ 
fdefine SLAPI_PLUGIN_AUDIT_DATA 
Idefine SLAPI_PLUGIN_AUDIT_FN 

/* managedsait control */ 
fdefine SLAPI_MANAGEDSAIT 

/* config stuff */ 

Idefine SLAPI_CONFIG_FILENAME 
Idefine SLAPI_CONFIG_LINENO 
fdefine SLAPI_CONFIG_ARGC 
fdefine SLAPI_CONFIG_ARGV 

/* operational params */ 
fdefine SLAPI_TARGET_DN 
fdefine SLAPI_REQCONTROLS 


/* modrdn params */ 

Idefine SLAPI_MODRDN_TARGET_UP 
fdefine SLAPI_MODRDN_TARGET 
fdefine SLAPI_MODRDN_NEWRDN 
Idefine SLAPI_MODRDN_DELOLDRDN 
Idefine SLAPIJIODRDNJIEWSUPERIOR 

/* extended Operation params */ 
fdefine SLAPI_EXT_OP_REQ_OID 
Idefine SLAPI_EXT_OP_REQ_VALUE 


/* Search result params */ 
fdefine SLAPI NENTRIES 


Output Parameters 

The following are the output parameters of the default database functions: 

/* common for internal plugin_ops */ 

SLAPI_PLUGIN_INT0P_RESU LT 
S LAPI_PLUGIN_INT0P_S EARCH_ENTRI ES 

SLAPI_C0NN_DN 
SLAPI_CONN_AUTHTYPE 

/# Types of authentication (for SLAPI_CONN_AÜTHTYPE) */ 
fdefine SLAPD_AUTH_NONE "none" 

fdefine SLAPD_AUTH_SIMPLE "simple" 

fdefine SLAPD_AUTH_SSL "SSL" 

Idefine SLAPD_AUTH_SASL "SASL " /* followed by the mechanism name */ 
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Appendix B. Supported iPlanet APIs 


The following iPlanet APIs are supported in this release. 

For pblock: 

int slapi_pblock_get( S1api_PBlock *pb, int arg, void *value ); 
int slapi_pblock_set( Slapi_PBlock *pb, int arg, void *value ); 

Sl api_PB1 ock *sl api_pbl ock_new(); 

void slapi_pblock_destroy( Slapi_PBlock* ); 

For memory management: 

char *slapi_ch_malloc( unsigned long size ); 
void slapi_ch_free( void *ptr ); 

char *slapi_ch_calloc( unsigned long nelem, unsigned long size ); 
char *slapi_ch_realloc(char *block, unsigned long size ); 
char *slapi_ch_strdup(char *s ); 

For sending results: 

void slapi_send_ldap_result( Slapi_PBlock *pb, int err, char 
*matched, char *text, 

int nentries, struct berval **urls); 

For LDAP specific objects: 

char *slapi_dn_normalize( char *dn ); 
char *slapi_dn_normalize_case( char *dn ); 
char *slapi_dn_ignore_case( char *dn ); 
char *slapi_dn_normalize_v3( char *dn ); 
char *slapi_dn_normalize_case_v3( char *dn ); 
char *slapi_dn_ignore_case_v3( char *dn ); 
char *slapi_dn_compare_v3(char *dnl, 
char* dn2); 

int slapi_dn_issuffix(char *dn, char *suffix); 
char *slapi_entry2str( Slapi_Entry *e, int 
*1en ); 

Slapi_Entry *slapi_str2entry( char *s, int flags ); 
int slapi_entry_attr_find( Slapi_Entry *e, char *type, 

Slapi_Attr **attr ); 

int slapi_entry_attr_delete( Slapi_Entry *e, char *type ); 

char *slapi_entry_get_dn( Slapi_Entry *e ); 
void slapi_entry_set_dn(Slapi_Entry *e, char *dn); 

Slapi_Entry *slapi_entry_al1oc(); 

Slapi_Entry *slapi_entry_dup( Slapi_Entry *e); 

init slapi_send_ldap_search_entry( Slapi_PB1ock *pb, 

Slapi_Entry *e, LDAPControl **ectrls, 
char **attrs, int attrsonly); 
void slapi_entry_free( Slapi_Entry *e ); 
int slapi_attr_get_values( Slapi_Attr *attr, struct berval 
***vals ); 


Slapi_Filter *slapi_str2fi 1 ter( char *str ); 
init slapi_fi1ter_get_choice( Slapi_Fi1ter*f ); 
init slapi_fi1ter_get_ava( Slapi_Fi1ter*f, char 
*type, struct berval **bvals ); 
void slapi_fi1ter_free( Slapi_Fi1ter*f, int recurse ); 
Slapi_Filter *slapi_fi 1 ter_list_first( Slapi_Fi 1 ter*f ); 

Sl api _Fi 1 ter *sl api_fi 1 ter_l i st_next (Sl api _Fi 1 ter*f, 

Sl api_Fi1ter*fprev); 

int sl api_is_connection_ssl( Slapi_PBlock *pPB, int *isSSL ); 
init s1api_get_c1ient_port( Slapi_PBlock *pPB, int *fromPort ); 
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For internal database operations: 

Slapi_PBlock *slapi_search_internal( char *base, int scope, char *filter, 
LDAPControl **controls, char **attrs, int attrsonly ); 

Slapi_PBlock *slapi_modify_internal( char *dn, LDAPMod **mods, 

LDAPControl **controls ); 

Slapi_PBlock *slapi_add_internal( char * dn, LDAPMod **attrs, 

LDAPControl **controls ); 

S1api_PB1ock *slapi_add_entry_internal( Slapi_Entry * e, 

LDAPControl **controls, 
int log_change ); 

S1api_PB1ock *slapi_delete_internal ( char * dn, 

LDAPControl **controls ); 

S1api_PB1ock *slapi_modrdn_internal( char * olddn, 
char * newrdn, char *newParent, 
int deloldrdn, LDAPControl **controls); 

void slapi_free_search_results_internal( S1api_PBlock *pb ); 

/* logging routines */ 

void slapi_printmessage(int catid, int level, int num, ... ); 

int slapi_1og_error( int severity, char *subsystem, char *fmt, ... ); 

For querying Server information: 

char **slapi_get_supported_saslmechanisms(); 

char **slapi_get_supported_extended_ops(); 

void slapi_register_supported_saslmechanism( char *mechanism ); 

int slapi_get_supported_controls(char ***ctrloidsp, 
unsigned long **ctrlopsp); 

void slapi_register_supported_control (char *controloid, 
unsigned long controlops); 

int slapi_control_present( LDAPControl **controls, 
char *oid, struct berval **val, 
int * iscritical); 

For logging routines: 

int slapi_1og_error( int severity, char *subsystem, char *fmt, ... ); 


slapi_pblock_get() 

slapi_pblock_get() receives the value of a name-value pair from a parameter block. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_pb1ock_get( Slapi_PB1ock *pb, int arg, void *value ); 

Parameters 

pb A parameter block. 

arg A pblock parameter that represents the data you want to receive. 
value A pointer to the value retrieved from the parameter block. 

Returns 

0 if successful, or -1 if there is an error. 


slapi_pblock_set() 

slapi_pblock_set() sets the value of a name-value pair in a parameter block. 
Syntax 

linclude "slapi-plugin.h" 

int slapi_pblock_set( Slapi_PB1ock *pb, int arg, void *value ); 
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Parameters 

pb A pointer to a parameter block. 

arg The ID of the name-value pair that you want to set. 

value A pointer to the value that you want to set in the parameter block. 

Returns 

0 if successful, or -1 if an error occurs. 


slapi_pblock_new() 

slapi_pblock_new() creates a new parameter block. 

Syntax 

linclude "slapi-plugin.h" 

S1 api_PBl ock *sl api_pbl ock_new(); 


Returns 

A pointer to the new parameter block is returned. 


slapi_pblock_destroy() 

slapi_pblock_destroy() frees the specified parameter block from memory. 

Syntax 

linclude "slapi-plugin.h" 

void slapi_pblock_destroy( S1api_PBlock *pb ); 

Parameters 


A pointer to the Parameter block that vou want to free. 


slapi_ch_malloc() 

slapi_ch_malloc() allocates space in memory, and calls the Standard malloc() C 
function. The slapd Server is terminated with an accompanying out of memory 
error message if memory cannot be allocated. 

Syntax 

linclude "slapi-plugin.h" 

char * slapi_ch_malloc( unsigned long size ); 

Parameters 

size The amount of space that you want memory allocated for. 


slapi_ch_calloc() 

slapi_ch_calloc() allocates space for an array of elements of a specified size. If calls 
the calloc() C function. The slapd Server is terminated with an accompanying out 
of memory error message if memory cannot be allocated. 

Syntax 

linclude "slapi-plugin.h" 
char * slapi_ch_cal1oc( unsigned long nelem, 
unsigned long size ); 


Parameters 

nelem The number of elements that you want to allocate memory for. 
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size The amount of memory of each element that you want to allocate 
memory for. 


slapi_ch_realloc() 

slapi_ch_realloc() changes the size of a block of allocated memory It calls the 
Standard realloc() C function. The slapd Server is terminated with an 
accompanying out of memory error message if memory cannot be allocated. 

Syntax 

linclude "slapi-plugin.h" 

char * slapi_ch_realloc( char *block, unsigned long size ); 

Parameters 

block A pointer to an existing block of allocated memory 

size The new amount of the block of memory you want allocated. 

Returns 

A pointer to a newly-allocated memory block with the requested size is 
returned. 


slapi_ch_strdup() 

slapi_ch_strdup() makes a copy of an existing string. It calls the Standard strdup() 
C function. The slapd Server is terminated with an accompanying out of memory 
error message if memory cannot be allocated. 

Syntax 

linclude "slapi-plugin.h" 

char * slapi_ch_strdup( char *s ); 

Parameters 

s Refers to the string you want to copy. 

Returns 

A pointer to a copy of the string is returned. If space cannot be allocated 
(for example, if no more virtual memory exists), a NULL pointer is 
returned. 


slapi_ch_free() 


slapi_ch_free() frees si 

pace allocated by the 

slapi_ch_malloc(). 

slapi_ch_calloc() 

slapi_ch_realloc(). 

md 

slapi ch strdup() 

functions. It does not set the pointer to 


NULL. 


Syntax 

linclude "slapi-plugin.h" 
void slapi_ch_free( void *ptr ); 

Parameters 

ptr A pointer to the block of memory that you want to free. If it is 
NULL, no action occurs. 


slapi_sendjdap_result() 

slapi_send_ldap_result() sends an LDAP result code back to the dient. 
Syntax 
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linclude "slapi-plugin.h" 

void slai_send_ldap_result( Slapi_PBlock *pb, int err, 
char *matched, char *text, int nentries, 
struct berval **urls ); 


Parameters 


pb A pointer to a parameter block. 

err The LDAP result code that you want sent back to the dient. 
matched 

Used to specify the portion of the target DN that can be matched 
when you send back an LDAP_NO_SUCH_OBJECT result. 
Otherwise you must pass NULL. 

text The error message that you want sent back to the dient. If you do 
not want an error message sent back, pass a NULL. 

nentries 

Used to specify the number of matching entries found when you 
send back the result code for an LDAP search Operation. 

urls Used to specify the array of the berval structure or to specify 
referral URLs when you send back either an 

LDAP_PARTIAL_RESULTS result code to an LDAP V2 dient or an 
LDAP_REFERRAL result code to an LDAP V3 dient. 


slapi_dn_normalize() 


Note: A variable passed in as the DN argu ment is also converted in-place. 


therefore this API is deprecated. See "slapi_dn_normalize_v3()" on page 20 


slapi_dn_normalize() converts a distinguished name (DN) to canonical format (that 
is, no leading or trailing spaces, no spaces between components, and no spaces 
around the equals sign). As an example, for the following DN: cn = John Doe, ou 
= Engineering , o = Darius the function returns: 
cn=John Doe,ou=Engineering,o=Darius 

Syntax 

linclude "slapi-plugin.h" 

char *slapi_dn_normalize( char *dn ); 

Parameters 

dn The DN that you want to normalize. 

Returns 

The normalized DN. 


slapi_dn_normalize_case() 


Note: A variable passed in as the DN argu ment is also converted in-place. 


therefore this API is deprecated. See "slapi_dn_normalize_case_v3()" on 


page 21 


slapi_dn_normalize_case() converts a distinguished name (DN) to canonical format 
(that is, no leading or trailing spaces, no spaces between components, and no 
spaces around the equals sign) and converts all characters to lower case. As an 
example, for the following DN: cn = John Doe, ou = Engineering, o = Darius the 
function returns: 
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cn=john doe,ou=engineering,o=darius 


Note: This function has the same effect as calling the slapi_dn_normalize() 
function followed by the slapi_dn_ignore_case() function. 

Syntax 

linclude "slapi-plugin.h" 

char *slapi_dn_normalize_case ( char *dn ); 

Parameters 

dn The DN that you want to normalize and convert to lower case. 

Returns 

The normalized DN with all characters in lower case. 


slapi_dn_ignore_case() 


Note: A variable passed in as the DN argu ment is also converted in-place. 


therefore this API is deprecated. See|"slapi_dn_ignore_case_v3()" on page 22 


slapi_dn_ignore_case() converts all of the characters in a distinguished name (DN) 
to lower case. As an example, for the following DN: cn = John Doe, ou = 
Engineering , o = Darius the function returns: 
cn = john doe , ou = engineering , o = darius 

Syntax 

linclude "slapi-plugin.h" 

char *slapi_dn_ignore_case ( char *dn ); 

Parameters 

dn The DN that you want to convert to lower case. 

Returns 

The DN with all characters in lower case. 


slapi_dn_normalize_v3() 

slapi_dn_normalize_v3() converts a distinguished name(DN) to canonical format 
(that is, no leading or trailing spaces, no spaces between components and no 
spaces around the equals sign). The API normalizes the attribute type name to the 
first textual type name in the Schema definition. Any semicolons used to separate 
relative distinguished names (RDN) are converted to commas. A compound RDN 
is sorted alphabetically by attribute name. The following is an example DN: 

userName=johnDOE + commonName = John Doe ; 

ou = Engineering , o = Darius the function returns: 

cn=John Doe+userName=johnDOE,ou=Engineering,o=Darius 

Special characters in a DN, if escaped using double-quotes, are converted to use 
backslash ( \ ) as the escape mechanism. For example, the following DN: 

cn="a + b", o=ibm, c=us the function returns 
cn=a \+ b,o=ibm,c=us 

An attribute value containing a backslash followed by a two-digit hex 
representation of a UTF-8 character is converted to the character representation. 
For example, the following DN: 

cn=\4A\6F\68\6E Doe,ou=Engineering,o=Darius 

the function returns cn=John Doe,ou=Engineering,o=Darius 
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A ber-encoded attribute value is converted to a UTF-8 value. For example, the 
following DN: 

cn=#04044A6F686E20446F65,ou=Engineering,o=Darius 

the function returns cn=John Doe,ou=Engineering,o=Darius 

An invalid DN returns NULL. 

Syntax 

linclude "slapi-plugin.h" 

char *slapi_dn_normalize_v3(char *dn); 

Parameters 

dn The DN that you want to normalize. It is not modified by the 
function. 

Returns 

The normalized DN in newly allocated space. 

Note: It is the responsibility of the caller to free the normalized DN. 


slapi_dn_normalize_case_v3() 

slapi_dn_normalize_v3() converts a distinguished name (DN) to canonical format 
(that is, no leading or trailing spaces, no spaces between components and no 
spaces around the equals sign). The API normalizes the attribute type name to the 
first textual type name in the Schema definition. Any semicolons used to separate 
relative distinguished names (RDN) are converted to commas. A compound RDN 
is sorted alphabetically by attribute name. The case of attribute types is changed to 
upper case in all cases. The case of the attribute values is converted to upper case 
only when the matching rules are case insensitive. It the matching rules for the 
attribute are case sensitive, the case of the attribute value is preserved. In the 
following example, userName is a case sensitive attribute and cn, ou and o are 
case insensitive. For example, the following DN: 

userName=johnDOE + commonName = John Doe ; 

ou = Engineering , o = Darius the function returns: 

CN=J0HN DOE+USERNAME=johnDOE,OU=ENG INEERING,0=DARIUS 

Special characters in a DN, it escaped using double-quotes, are converted to use 
backslash ( \ ) as the escape mechanism. For example, the following DN: 

cn="a + b", o=ibm, c=us the function returns 
CN=A \+ B,0=IBM,C=US 

An attribute value containing a backslash followed by a two-digit hex 
representation of a UTF-8 character is converted to the character representation. 

For example, the following DN: 

cn=\4A\6F\68\6E Doe,ou=Engineering,o=Darius 

the function returns CN=J0HN DOE,0U=ENGINEERING,0=DARI US 

A ber-encoded attribute value is converted to a UTF-8 value. For example, the 
following DN: 

cn=#04044A6F686E20446F65,ou=Engineering,o=Darius 

the function returns CN=J0HN DOE,0U=ENGINEERING,0=DARI US 

An invalid DN returns NULL. 

Syntax 

linclude "slapi-plugin.h" 

char *slapi_dn_normalize_case_v3(char *dn); 
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Parameters 

dn The DN that you want to normalize and convert to lower case. It is 
not modified by the function. 

Returns 

The normalized DN in newly allocated space. 

Note: It is the caller's responsibility to free the normalized DN. 


slapi_dnJgnore_case_v3() 

slapi_dn_ignore_case_v3() normalizes a distinguished name (DN) and converts all 
of the characters to lower case. For example, the following DN: 

userName=johnDOE + commonName = John Doe ; 
ou = Engineering , o = Darius 
the function returns: 

cn=john doe+username=johndoe,ou=engineering,o=darius 

Syntax 

linclude "slapi-plugin.h" 

char *slapi_dn_ignore_case _v3(char *dn); 

Parameters 

dn The DN that you want to normalize and convert to lower case. 

Returns 

The DN normalized with all characters in lower case. 

Note: It is the caller's responsibility to free the normalized DN. 


slapi_dn_compare_v3() 

slapi_dn_compare_v3() compares two distinguished names (DN). 

Syntax 

linclude "slapi-plugin.h" 

char *slapi_dn_compare_v3(char *dnl, char* dn2); 

Parameters 

dnl A DN that you want to compare. 
dn2 A DN that you want to compare. 

Returns 

• Less than 0 it the value of dnl is lexicographically less than dn2. 

• 0 it the value of dnl is lexicographically equal to dn2. 

• Greater than 0 it the value of dnl is lexicographically greater than dn2. 


slapi_dn_issuffix() 

slapi_dn_issuffix() determines whether a DN is equal to the specified suffix. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_dn_issuffix( char *dn, char *suffix ); 


Parameters 

dn 


22 Server Plug-ins Reference 


The DN that you want to check. 





suffix The suffix you want compared against the DN. 

Returns 

A 1 is returned if the specified DN is the same as the specified suffix, or a 
0 is returned if the DN is not the same as the suffix. 


slapi_entry2str() 

slapi_entry2str() generates a description of an entry as a string. The LDIF string 
has the following format: 

dn: <dn >\n 
*[<attr>: <value>\r\] 

* [<ot tr>:: <base_64_encoded_value >] 


where: 

* The operator when it preceeds an element indicates repetition. The full 

form is: <a>*<b> where <a> and <b> are optional decimal values, 
indicating at least <a> and at most <b> occurrences of element. 

Default values are 0 and infinity so that *<element> allows any number, 
including zero; l*<element> requires at least one; 3*3<element> allows 
exactly 3 and 1*2 <element> allows one or two. 

dn Distinguished name 

attr Attribute name 

\n New line 

value Attribute value 

For example: 

dn: uid=rbrown2, ou=People, o=airius.com 
cn: Robert Brown 
sn: Brown 


When you no longer need to use the string, you can free it from memory by 
calling the slapi_ch_free() function. 


Call the slapi_str2entry() function to convert a string description in this format to 
an entry of the Slapi_Entry data type. 


Syntax 

linclude "slapi-plugin.h" 

char *slapi_entry2str( Slapi_Entry *e, int *len ); 

Parameters 


e Address of the entry that you want to generate a description for. 

len Address of the length of the returned string. 

Returns 

The description of the entry as a string is returned or NULL if an error 
occurs. 
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slapi_str2entry() 

slapi_str2entry() converts an LDIF description of a directory entry (a string value) 
into an entry of the Slapi_Entry data type that can be passed to other API 
functions. 


Note: This function modifies the s string argument, and you must make a copy of 
this string betöre it is called. 


If there are errors during the conversion process, the function retums a NULL 
instead of the entry. 


When you are through working with the entry, call the slapi entry_free() 


To convert an entry to a string description, call slapi_entry2str() 


function. 


Syntax 

linclude "slapi-plugin.h" 

Slapi_Entry *slapi_str2entry( char *s, int flags ); 


Parameters 


s The description of an entry that you want to convert. 

flags Specifies how the entry must be generated. 


The flags argument can be one of the following values: 

SLAPI_STR2ENTRY_REMOVEDUPVALS 

Removes any duplicate values in the attributes of the entry. 

SLAPI_STR2ENTRY_ADDRDNVALS 

Adds the relative distinguished name (RDN) components. 

Returns 

A pointer to the Slapi_Entry structure representing the entry is returned, or 
a NULL is returned if the string cannot be converted, for example, if no 
DN is specified in the string. 


slapi_entry_attr_find() 

slapi_entry_attr_find() determines if an entry has a specified attribute. If it does, 
this function returns that attribute. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_entry_attr_find( Slapi_Entry *e, char *type, 

S1api_Attr **attr ); 

Parameters 

e An entry that you want to check. 

type Indicates the name of the attribute that you want to check. 

attr A pointer to the attribute (assuming that the attribute is in the 
entry). 

Returns 

A 0 is returned if the entry contains the specified attribute, or -1 is 
returned if it does not. 
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slapi_entry_attr_delete() 

slapi_entry_attr_delete() deletes an attribute from an entry. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_entry_attr_delete (Slapi_Entry *e, char *type); 

Parameters 

e The entry from which you want to delete the attribute. 

type Indicates the name of the attribute that you want to delete. 

Returns 

A 0 is returned if the attribute is successfully deleted, a 1 is returned if the 
specified attribute is not part of the entry, or -1 is returned if an error has 
occurred. 


slapi_entry_get_dn() 

slapi_entry_get_dn() receives the DN of the specified entry. 

Syntax 

linclude "slapi-plugin.h" 

char *slapi_entry_get_dn( Slapi_Entry *e ); 

Parameters 

e Indicates an entry that contains the DN you want. 

Returns 

The DN of the entry is returned. A pointer to the actual DN in the entry is 
returned, not a copy of the DN. 


slapi_entry_set_dn() 

slapi_entry_set_dn() sets the DN of an entry. It sets the pointer to the DN that you 
specify. 

Note: Because the old DN is not overwritten and is still in memory, you need to 
first call slapi_entry_get_dn() to get the pointer to the current DN, free the 
DN, and then call slapi_entry_set_dn() to set the pointer to your new DN. 

Syntax 

linclude "slapi-plugin.h" 

void *slapi_entry_set_dn( Slapi_Entry *e char *dn ); 

Parameters 

e Indicates the entry to which you want to assign the DN. 

dn The DN that you want to assign to the entry. 


slapi_entry_alloc() 


slapi_entry_alloc() allocates memory for a new entry of the Slapi_Entry data type. 
It returns an empty Slapi_Entry structure. You can call other front-end functions to 
set the DN and attributes of this entry. When you are through working with the 
entry, free it by calling the slapi_entry_free() function. 

Syntax 
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linclude "slapi-plugin.h" 
Slapi_Entry *sl api_entry_al loc(); 


Returns 

A pointer to the newly allocated entry of the Slapi_Entry data type is 
returned. If space cannot be allocated (for example, if no more virtual 
memory exists), the Server program ends. 


slapi_entry_dup() 


slapi_entry_dup() makes a copy of an entry, its DN, and its attributes. You can call 
other front-end functions to change the DN and attributes of this copy of an 
existing Slapi E ntry structure. Wh en you are through working with the entry, free 


if by calling the slapi_entry_free() 


function. 


Syntax 

linclude "slapi-plugin.h" 

Slapi_Entry *slapi_entry_dup( Slapi_Entry *e ); 


Parameters 


e The entry that you want to copy. 

Returns 

The new copy of the entry. If the structure cannot be duplicated (for 
example, if no more virtual memory exists), the Server program ends. 


slapi_sendjdap_search_entry() 

slapi_send_ldap_search_entry() sends an entry found by a search back to the dient. 
Syntax 

linclude "slapi-plugin.h" 

int slapi_send_ldap_search_entry( S1api_PB1ock *pb, 

Slapi_Entry *e, LDAPControl **ectrls, 
char **attrs, int attrsonly ); 

Parameters 

pb The parameter block. 

e The pointer to the Slapi_Entry structure representing the entry that 

you want to send back to the dient. 

ectrls The pointer to the array of LDAPControl structures that represent 
the Controls associated with the search request. 

nttrs Attribute types specified in the LDAP search request. 

attrsonly 

Specifies whether the attribute values must be sent back with the 
result. 

• If set to 0, the values are included. 

• If set to 1, the values are not included. 

Returns 

A 0 is returned if successful, a 1 is returned if the entry is not sent (for 
example, if access control did not allow it to be sent), or a -1 is returned if 
an error occurs. 
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slapi_entry_free() 

slapi_entry_free() frees an entry, its DN, and its attributes from memory. 

Syntax 

linclude "slapi-plugin.h" 

void slapi_entry_free( Slapi_Entry *e ); 

Parameters 

e An entry that you want to free. If it is NULL, no action occurs. 


slapi_attr_get_values() 

slapi_attr_get_values() receives the value of the specified attribute. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_attr_get_values( Slapi_Attr *attr, struct berval 
***vals ); 

Parameters 

nttr An attribute that you want to get the flags for. 

vnls When slapi_attr_get_values() is called, vals is set to a pointer that 
indicates a NULL-terminated array of berval structures 
(representing the values of the attribute). Do not free the array; the 
array is part of the actual data in the attribute, not a copy of the 
data. 

Returns 

A 0 is returned if it is successful. 


slapi_str2filter() 


slapi_str2filter() converts a string description of a search filter into a filter of the 
Slapi_Filter type. W hen you are done working with this filter, free the Slapi_Filter 


structure by calling slapi_filter_free() 


Syntax 

#include "slapi-plugin.h" 

Slapi_Fi 1 ter *slapi_str2fi 1 ter( char *str ); 


Parameters 


sfr A string description of a search filter. 

Returns 

The address of the Slapi_Filter structure representing the search filter is 
returned, or a NULL is returned if the string cannot be converted (for 
example, if an empty string is specified or if the filter syntax is incorrect). 


slapi_filter_get_choice() 

slapi_filter_get_choice() gets the type of the specified filter (for example, 
LD AP_FILTER_EQU ALITY). 

Syntax 

linclude "slapi-plugin.h" 

int slapi_filter_get_choice( Slapi_Fi 1 ter *f ); 

Parameters 
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The filter type that you want to get. 


/ 

Returns 

One of the following values is returned: 

LDAP_FILTER_AND (AND filter) 

For example: (&(ou=Accounting) (1 =Sunnyval e)) 

LDAP_FILTER_OR (OR filter) 

For example: (| (ou=Accounti ng) (1 =Sunnyval e)) 

LDAP_FILTER_NOT (NOT filter) 

For example: (! (1 =Sunnyval e)) 

LDAP_FILTER_EQUALITY (equals filter) 

For example: (ou=Accounti ng) 

LDAP_FILTER_SUBSTRINGS (substring filter) 

For example: (ou=Account*Department) 

LDAP_FILTER_GE ("greater than or equal to" filter) 

For example: (supportedLDAPVersion>=3) 

LDAP_FILTER_LE ("less than or equal to" filter) 

For example: (supportedLDAPVersion<=2) 

LDAP_FILTER_PRESENT (presence filter) 

For example: (mai 1 =*) 

LDAP_FILTER_APPROX (approximation filter) 

For example: (oiT=Sales) 


slapi_filter_get_ava() 

slapi_filter_get_ava() gets the attribute type and the value from the filter. This 
applies only to filters of the types LDAP_FILTER_EQUALITY / LDAP_FILTER_GE / 
LDAP_FILTER_LE, LDAP_FILTER_APPROX. These filter types generally compare 
a value against an attribute. For example: (cn=John Doe) This filter finds entries in 
which the value of the cn attribute is equal to John Doe. 

Calling the slapi_filter_get_ava() function gets the attribute type and value from 
this filter. In the case of the example, calling the slapi_filter_get_ava() function gets 
the attribute type cn and the value John Doe. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_fi1ter_get_ava( Slapi_Filter *f, 

char **type, struct berval **bval ); 

Parameters 

/ The address of the filter from which you want to get the attribute 

and value. 

type The pointer to the attribute type of the filter. 

bvnl The pointer to the address of the berval structure that contains the 

value of the filter. 

Returns 

A 0 is returned if successful, or a -1 is returned if the filter is not one of the 
types listed. 
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slapi_filter_free() 

slapi_filter_free() frees the specified filter and (optionally) the set of filters that 
comprise it. For example, the set of filters in an LDAP_FILTER_AND type filter. 

Syntax 

linclude "slapi-plugin.h" 

void slapi_fi1ter_free( Slapi_Filter *f, int recurse ); 

Parameters 

/ The filter that you want to free. 


recurse 

If set to 1, it recursively frees all filters that comprise this filter. If 
set to 0, it only frees the filter specified by the f parameter. 


slapi_filter_list_first() 

slapi_filter_list_first() gets the first filter that makes up the specified filter. This 
applies only to filters of the types LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, 
LDAP_FILTER_LE, and LDAP_FILTER_APPROX. These filter types generally 
consist of one or more other filters. For example, if the filter is: 

(&(ou=Accounti ng) (1 =Sunnyval e) ) the first filter in this list is: (ou=Accounting). 
Use the slapi_filter_list_first() function to get the first filter in the list. 

Syntax 

linclude "slapi-plugin.h" 

Slapi_Fi1ter *slapi_fi1ter_list_first 
( Sl api_Fi 1 ter *f ); 

Parameters 

/ The filter from which you want to get the first component. 

Returns 

The first filter that makes up the filter specified by the f parameter is 
returned. 


slapi_filterjist_next() 

slapi_filter_list_next() gets the next filter (following fprev) that makes up the 
specified filter f. This applies only to filters of the types 
LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, and 
LDAP_FILTER_APPROX. These filter types generally consist of one or more other 
filters. For example, if the filter is: (&(ou=Accounti ng) (1 =Sunnyval e) ) the next filter 
after (ou=Accounti ng) in this list is: (USunnyvale). Use the slapi_filter_list_first() 
function to get the first filter in the list. 


To iterate through all filters that make up a specified filter, call the 
slapi_filter_list_first() function and then call slapi_filter_list_next(). 

Syntax 

linclude "slapi-plugin.h" 

Sl api_Fi 1 ter *slapi_filter_list_next( Sl api_Fi 1 ter 
*f, Sl api_Fi 1 ter *fprev ); 

Parameters 


/ 


The filter from which you want to get the next component (after 
fprev). 
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fprev A filter within the filter specified by the f parameter. 

Returns 

The next filter (after fprev) that makes up the filter specified by the f 
parameter is returned. 


slapi_is_connection_ssl() 

slapi_is_connection_ssl() is used by the Server to determine whether the connection 
between it and a dient is through a Secure Socket Layer (SSL). 

Syntax 

linclude "slapi-plugin.h" 

int slapi_is_connection_ssl( Slapi_PBlock *pPB, 
int *isSSL); 

Parameters 

pPB Address of a Parameter Block. 

isSSL Address of the output parameter. A 1 is returned if the connection 
is through SSL or a 0 is returned if it is not through SSL. 

Returns 

A 0 is returned if successful. 


slapi_get_client_port() 

slapi_get_client_port() is used by the Server to determine the port number used by 
a dient to communicate to the Server. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_get_client_port( Slapi_PBlock *pPB, 

int *fromPort); 

Parameters 

pPB Address of a Parameter Block. 
fromPort 

Address of the output parameter. It is the port number used by the 
dient. 


Returns 

A 0 is returned if successful. 


slapi_search_internal() 

slapi_search_internal() performs an LDAP search Operation to search the directory 

from your plug-in. 

Syntax 

linclude "slapi-plugin.h" 

Slapi_PBlock *slapi_search_internal( char *base, int scope, 
char *filter, LDAPControl **controls, 
char **attrs, int attrsonly ); 

Parameters 

base The DN of the entry that serves as the starting point for the search. 
For example, setting base o=Acme Industry, c=US restricts the 
search to entries at Acme Industry located in the United States. 
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scope 


Defines the scope of the search. It can be one of the following 
values: 

• LDAP_SCOPE_BASE searches the entry that is specified by base. 

• LDAP_SCOPE_ONELEVEL searches all entries one level beneath 
the entry specified by base. 

• LDAP_SCOPE_SUBTREE searches the entry specified by base. It 
also searches all entries at all levels beneath the entry specified 
by base . 

filter The string representation of the filter to apply in the search. 

Controls 

The NULL-terminated array of LDAP Controls that you want 
applied to the search Operation. 

attrs The NULL-terminated array of attribute types to retum from 

entries that match the filter. It you specify a NULL, all attributes 
are retumed. 

attrsonly 

Specifies whether or not attribute values are returned along with 
the attribute types. It can have the following values: 

• A 0 specifies that both attribute types and attribute values are 
returned. 

• A 1 specifies that only attribute types are returned. 

Returns 

slapi_free_search_results_internal() and slapi_pblock_destroy() need to be 
called to free the search results and the pblock that is retumed by 
slapi_search_internal. 


slapi_modify_internal() 

slapi_modify_internal() performs an LDAP modify Operation to modify an entry in 
the directory from a plug-in. 

Unlike the Standard LDAP modify Operation, no LDAP result code is retumed to a 
dient; the result code is placed instead in a parameter block that is returned by the 
function. 

Syntax 

linclude "slapi-plugin.h" 

S1 api_PBlock *slapijnodify_internal ( char *dn, 

LDAPMod **mods, 

LDAPControl **controls, int 1 ); 

Parameters 

dn A distinguished name (DN) of the entry that you want to modify. 

mods A pointer to a NULL-terminated array of pointers to LDAPMod 
structures representing the attributes that you want to modify. 

Controls 

A NULL-terminated array of LDAP Controls. 

I Included for compatibility only. It is not used. 


Returns 

A new parameter block with the following parameter set is returned: 
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• SLAPI_PLUGIN_INTOP_RESULT specifies the LDAP result code for the 
internal LDAP Operation. 


slapi_addjnternal() 

slapi_add_internal() performs an LDAP add Operation in Order to add a new 
directory entry (specified by a DN and a set of attributes) from your plug-in. 
Unlike the Standard LDAP add Operation, no LDAP result code is returned to a 
dient. The result code is instead placed in a parameter block that is returned by 
the function. 

Syntax 

linclude "slapi-plugin.h" 

Slapi_PBlock *slapi_add_internal( char * dn, 

LDAPMod **mods, 

LDAPControl **controls, int 1 ); 

Parameters 

dn The Distinguished name (DN) of the entry that you want to add. 

mods A pointer to a NULL-terminated array of pointers to LDAPMod 
structures representing the attributes of the new entry that you 
want to add. 

Controls 

A NULL-terminated array of LDAP Controls that you want applied 
to the add Operation. 

I Included for compatibility only. It is not used. 

Returns 

A new parameter block with the following parameter set is returned: 

• SLAPI_PLUGIN_INTOP_RESULT specifies the LDAP result code for the 
internal LDAP Operation. 


slapi_add_entry_internal() 

slapi_add_entry_internal() performs an LDAP add Operation to add a new 
directory entry (specified by an Slapi_Entry structure) from a plug-in function. 
Unlike the Standard LDAP add Operation, no LDAP result code is returned to a 
dient. Instead, the result code is placed in a parameter block that is returned by 
the function. 

Note: To add an entry specified by a string DN and an array of LDAPMod 
structures, call slapi_add_internal() instead. 

Syntax 

linclude "slapi-plugin.h" 

Slapi_PBlock *slapi_add_entry_internal ( Slapi_Entry * e, 

LDAPControl **controls, int 1 ); 

Parameters 

mods A pointer to an Slapi_Entry structure representing the new entry 
that you want to add. 

Controls 

A NULL-terminated array of LDAP Controls that you want applied 
to the add Operation. 

I Included for compatibility only. It is not used. 
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Returns 

A new parameter block with the following the following parameter set is 
returned: 

• SLAPI_PLUGIN_INTOP_RESULT specifies the LDAP result code for the 
internal LDAP Operation (for example, LDAP_SUCCESS if the Operation 
is successful or LDAP_PARAM_ERROR if an invalid parameter is used). 
If the DN of the new entry has a suffix that is not served by the 
Directory Server, SLAPI_PLUGIN_INTOP_RESULT is set to 
LDAP_REFERRAL. 


slapi_deletejnternal() 

slapi_delete_internal() performs an LDAP delete Operation in order to remove a 
directory entry when it is called from your plug-in. 

Unlike the Standard LDAP delete Operation, no LDAP result code is returned to a 
dient. The result code is instead placed in a parameter block that is returned by 
the function. 

Syntax 

linclude "slapi-plugin.h" 

S1api_PBlock *slapi_delete_internal( char * dn, 

LDAPControl **controls, int 1 ); 

Parameters 

dn The distinguished name (DN) of the entry that you want to delete. 
Controls 

A NULL-terminated array of LDAP Controls that you want applied 
to the delete Operation. 

I Included for compatibility only. It is not used. 

Returns 

A new parameter block with the following parameter set is returned: 

• SLAPI_PLUGIN_INTOP_RESULT specifies the LDAP result code for the 
internal LDAP Operation. 


slapi_modrdn_internal() 

slapi_modrdn_intemal() performs an LDAP modify RDN Operation in order to 
rename a directory entry from your plug-in. 

Unlike the Standard LDAP modify RDN Operation, no LDAP result code is 
returned to a dient. The result code is instead placed in a parameter block that is 
returned by the function. 

Syntax 

linclude "slapi-plugin.h" 

S1api_PBlock *slapi_modrdn_internal( char * olddn, 

char * newrdn, int deloldrdn, LDAPControl **controls, 
int 1); 


Parameters 

olddn The distinguished name (DN) of the entry that you want to 
rename. 

newdn The new relative distinguished name (RDN) of the entry. 
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deloldrdn 

Specifies whether or not you want to remove the old RDN from 
the entry. 

• If a 1, remove the old RDN. 

• If a 0, leave the old RDN as an attribute of the entry. 

Controls 

A NULL-terminated array of LDAP Controls that you want applied 
to the modify RDN Operation. 

I Included for compatibility only. It is not used. 

Returns 

A new parameter block with the following parameter set is returned: 

• SLAPI_PLUGIN_INTOP_RESULT specifies the LDAP result code for the 
internal LDAP Operation. 


slapi_free_search_results_internal() 

slapi_free_search_results_internal() frees the memory associated with LDAP entries 
returned by the search. 

Syntax 

linclude "slapi-plugin.h" 

void slapi_free_search_results_internal( S1api_PBlock *pb); 

Parameters 


Is a pointer to a Parameter Block that is returned by a 
slapi_free_search_internal function. 


slapi_get_supported_saslmechanisms() 


slapi_get_supported_saslmechanisms() obtains an array of the supported Simple 
Authentication and Securit y Layer (SASL) mechanisms names. Registe r new SASL 
mechanisms by calling the slapi_register_supported_saslmechanism() function. 


Syntax 

linclude "slapi-plugin.h" 

char ** slapi_get_supported_saslmechanisms( void ); 


Returns 

A pointer to an array of SASL mechanisms names supported by the Server 
is returned. 


slapi_get_supported_extended_ops() 

slapi_get_supported_extended_ops() gets an array of the object IDs (OIDs) of the 
extended operations supported by the Server. Register new extended operations by 
putting the OID in the SLAPI_PLUGIN_EXT_OP_OIDLIST parameter and calling 
the slapi_pblock_set() function. 

Syntax 

linclude "slapi-plugin.h" 

char **slapi_get_supported_extended_ops( void ); 

Returns 

A pointer to an array of the OIDs of the extended operations supported by 
the Server is returned. 
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slapi_register_supported_saslmechanism() 

slapi_register_supported_saslmechanism() registers the specified Simple 
Authentication and Security Layer (SASL) mechanism with the Server. 

Syntax 

linclude "slapi-plugin.h" 

void slapi_register_supported_saslmechanism( char *mechanism ); 
Parameters 

mechanism 

Indicates the name of the SASL mechanism. 


slapi_get_supported_controls() 


slapi_get_supported_controls() obtains an array of OIDs, which represent the 
Controls supported by the directory Server. Register new Controls by calling the 


slapi_register_supported_control()| function. 


Syntax 

linclude "slapi-plugin.h" 

int slapi_get_supported_controls( char ***ctrloidsp, 
unsigned long **ctrlopsp ); 


Parameters 


ctrloidsp 

A pointer to an array of OIDs, which represent the Controls 
supported by the Server. 

ctrlopsp 

A pointer to an array of IDs which specify LDAP operations that 
Support each control. 

Returns 

A 0 is returned if successful. 


slapi_register_supported_control() 

slapi_register_supported_control() registers the specified control with the Server. It 
also associates the control with an OID. When the Server receives a request that 
specifies this OID, the Server makes use of this information in Order to determine if 
the control is supported. 

Syntax 

linclude "slapi-plugin.h" 

void slapi_register_supported_control( char *controloid, 
unsigned long controlops ); 

Parameters 

controloid 

The OID of the control you want to register. 
controlops 

The Operation that the control is applicable to. It can have one or 
more of the following values: 

SLAPI_OPERATION_BIND 

The specified control that applies to the LDAP bind 
Operation. 
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SLAPI_OPERATION_UNBIND 

The specified control that applies to the LDAP unbind 
Operation. 

SLAPI_OPERATION_SEARCH 

The specified control that applies to the LDAP search 
Operation. 

SLAPI_OPERATION_MODIFY 

The specified control that applies to the LDAP modify 
Operation. 

SLAPI_OPERATION_ADD 

The specified control that applies to the LDAP add 
Operation. 

SLAPI_OPERATION_DELETE 

The specified control that applies to the LDAP delete 
Operation. 

SLAPI_OPERATION_MODDN 

The specified control that applies to the LDAP modify DN 
Operation. 

SLAPI_OPERATION_MODRDN 

The specified control that applies to the LDAP V3 modify 
RDN Operation. 

SLAPI_OPERATION_COMPARE 

The specified control that applies to the LDAP compare 
Operation. 

SLAPI_OPERATION_ABANDON 

The specified control that applies to the LDAP abandon 
Operation. 

SLAPI_OPERATION_EXTENDED 

The specified control that applies to the LDAP V3 extended 
Operation. 

SLAPI_OPERATION_ANY 

The specified control that applies to any LDAP Operation. 

SLAPI_OPERATION_NONE 

The specified control that applies to none of the LDAP 
opera tions. 


slapi_control_present() 

slapi_control_present() determines whether or not the specified OID identifies a 
control that might be present in a list of Controls. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_control_present( LDAPControl **controls, char *oid, 
struct berval **val, int *iscritical ); 


Parameters 

Controls 
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oid 


The list of Controls that you want to check. 

Refers to the OID of the control that you want to find. 



val Specifies the pointer to the berval structure containing the value of 
the control (if the control is present in the list of Controls). 

iscriticnl 

Specifies whether or not the control is critical to the Operation of 
the Server (if the control is present in the list of Controls). 

• A 0 means that the control is not critical to the Operation. 

• A 1 means that the control is critical to the Operation. 

Returns 

A 1 is returned if the specified control is present in the list of Controls, or a 
0 if the control is not present. 


slapi_log_error() 

Writes a message to the error log for the directory Server. 

Syntax 

linclude "slapi-plugin.h" 

int slapi_log_error( int severity, char *subsystem, char *fmt, ... ); 
Parameters 

severity 

Level of severity of the message. In combination with the severity 
level specified by ibm-slapdSysLogLevel in the ibmslapd.conf file, 
determines whether or not the message is written to the log. The 
severity must be one of the following: 

• LDAP_MSG_LOW 

• LDAP_MSG_MED 

• LDAP_MSG_HIGH 

The following entry in the ibmslapd.conf file results in a medium 
logging level: 

#ibm-slapdSysLogLevel must be one of 1/m/h (l=terse, h=verbose) 
ibm-slapdSysLogLevel: m 

With this example in your ibmslapd.conf file, log messages with 
severity LDAP_MSG_HIGH or LDAP_MSG_MED are logged. The 
messages with severity LDAP_MSG_LOW are not logged. If the 
slapdSysLogLevel is set to h, all messages are logged. 

Subsystem 

Name of the Subsystem in which this function is called. The string 
that you specify here appears in the error log in the following 
format: 

<subsystem>: <message> 

fmt, ... Message that you want written. This message can be in 
printf()-style format. For example: 

.... "%s\n", myString); 

Returns 

A 0 is returned if successful, -1 if an unknown severity level is specified. 
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Appendix C. Plug-in examples 


The following sample C code creates a simple SASL bind plugin that uses the 
mechanism SAMPLE_BIND. It compares the password that is sent across the wire 
to the passwored stored in the directroy for the given bind DN. 

finclude <stdio.h> 

#include <string.h> 

#include <strings.h> 

finclude <slapi-plugin.h> 

#define FALSE 0 

/* Let the next plugin try the Operation */ 

#define NEXTPLUGIN 0 

/* We handled the Operation, so don't run any other plugins */ 

#define STOP_PLUGIN_SEARCH 1 

/* SASL mechanism type */ 

#define SAMPLE_MECH "SAMPLE_BIND" 

/* Subsystem to use for slapi_log_error calls */ 

#define SAMPLE_SUBSYSTEM "SAMPLE" 

/* Filter used when searching for the entry DN */ 

#define FILTER "objectclass=*" 

/* Password attribute name */ 

#define PWATTR "userpassword" 

/* Forward declaration of our bind plugin function */ 
int sampleBind(Slapi_PBlock *pb); 

/* Initialization function */ 
int samplelnit(Slapi_PBlock *pb) 

{ 

int arge = 0; 
char ** argv = NULL; 

/* to register the Sample_Bind function as the pre-operation 
* bind funtion 
*/ 

if (slapi_pblock_set( pb, SLAPI_PLUGIN_PRE_BIND_FN, (void*) sampleBind ) != 0) 

{ 

slapi_log_error( LDAP_MSG_L0W, SAMPLE_SUBSYSTEM, 

"samplelnit couldn't set plugin function\n"); 

return (-1); 

} 


/* Get the plugin argument count. These arguments are defined 
* in the plug-in directive in the configuration file. 

*/ 

if (slapi_pblock_get( pb, SLAPI_PLUGIN_ARGC, &argc ) != 0) 

{ 

slapi_log_error( LDAP_MSG_L0W, SAMPLE_SUBSYSTEM, 
"samplelnit couldn't get argc\n"); 

return (-1); 

} 


/* Get the plugin argument array */ 

if(slapi_pblock_get( pb, SLAPI_PLUGIN_ARGV, &argv ) != 0) 

{ 

s1api_1og_error( LDAP_MSG_L0W, SAMPLE_SUBSYSTEM, 
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"samplelnit couldn't get argv\n"); 

return (-1); 

} 

/* Low "severity" means high importance. */ 
slapi_log_error( LDAP_MSG_LOW, SAMPLEJUBSYSTEM, 

"Hello from sample\n" ); 


/* 

* Register SAMPLE_BIND as one of the supported SASL mechanisms 

* so that it shows up when the RootDSE is queried. 

*/ 

slapi_register_supported_saslmechanism(SAMPLE_MECH); 
return LDAP_SUCCESS; 

} 

/* 

* Function to get the password for the specified dn. 

*/ 

int getEntryPassword(char *dn, char ** passwd) 

{ 

Slapi_PBlock *pb = NULL; 
int rc = LDAPJUCCESS; 
int numEntries = 0; 

Slapi_Entry **entries = NULL; 

Slapi_Attr *a = NULL; 

struct berval **attr_vals = NULL; 


/* 

* Do an internal search to get the entry for the given dn 
*/ 

pb = slapi_search_internal(dn, /* Entry to retrieve */ 

LDAP_SCOPE_BASE, 

/* Only get the entry asked for */ 

FILTER, /* Search filter */ 

NULL, /* No Controls */ 

NULL, /* Get all attributes */ 

FALSE); 

/* Get attribute values (names only is false) */ 


if (pb == NULL) 

( 

slapi_log_error( LDAP_MSG_LOW, SAMPLE_SUBSYSTEM, 

"Search failed for dn = %s\n", dn); 
return (LDAP_OPERATIONS_ERROR); 

} 

/* Get the return code from the search */ 
slapi_pblock_get( pb, SLAPI_PLUGIN_INTOP_RESULT, &rc); 
if (rc != LDAP_SUCCESS) 

{ 

/* Search failed */ 
slapi_pblock_destroy( pb ); 
return (rc); 

} 

/* Get the number of entries returned from the search */ 
slapi_pblock_get( pb, SLAPI_NENTRIES, &numEntries ); 
if (numEntries == 0) 

{ 

/* Couldn't find entry */ 
slapi_free_search_results_internal ( pb ); 
slapi_pblock_destroy( pb ); 
return (LDAP_NO_SUCH_OBJECT); 

} 
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/* Get the entries */ 

slapi_pblock_get( pb, SLAPI_PLUGIN_INTOP_SEARCH_ENTRIES, &entries ); 


/* 

* Since we did a base level search, there can only be one entry returned. 

* Get the value of the "userpassword" attribute from the entry. 

*/ 

if (slapi_entry_attr_find( entries[0], PWATTR, &a ) == 0) 

{ 

/* Copy the password into the out parameter */ 
slapi_attr_get_values( a, &attr_vals ); 

(*passwd) = slapi_ch_strdup( attr_vals[0]->bv_val ); 

} 

el se 

{ 

/* No userpassword attribute */ 
slapi_free_search_results_internal( pb ); 
slapi_pblock_destroy( pb ); 
return (LDAP_INAPPROPRIATE_AUTH); 

} 


slapi_free_search_results_internal( pb ); 
slapi_pblock_destroy( pb ); 
return (LDAPSUCCESS); 


/* Function to handle a bind request */ 
int sampleBind(Slapi_PBlock *pb) 

{ 

char * mechanism = NULL; 

char * dn = NULL; 

char * passwd = NULL; 

char * connDn = NULL; 

char * aString = NULL; 

struct berval * credentials = NULL; 

int rc = LDAP_SUCCESS; 

/* Get the target DN */ 

if (s1api_pblock_get( pb, SLAPI_BIND_TARGET, &dn ) != 0) 

{ 

slapi_log_error( LDAP_MSG_LOW, SAMPLE_SUBSYSTEM, 

"sampleBind couldn't get bind target\n"); 
return (NEXTPLUGIN); 

} 


/* Get the password */ 

if (slapi_pbl ock_get( pb, SLAPI_BIND_CREDENTIALS, &credentials ) != 0) 

{ 

slapi_log_error( LDAP_MSG_LOW, SAMPLE_SUBSYSTEM, 

"sampleBind couldn't get bind target\n"); 
return (NEXTPLUGIN); 

} 


/* Get the bind mechanism */ 

if (slapi_pblock_get( pb, SLAPI_BIND_SASLMECHANISM, &mechanism ) != 0) 

{ 

s1api_1og_error( LDAP_MSG_L0W, SAMPLE_SUBSYSTEM, 

"sampleBind couldn't get bind target\n"); 
return (NEXTPLUGIN); 

} 


/* 

* If the requested mechanism isn't SAMPLE, then we're not going to 

* handle it. 

*/ 

if ((mechanism == NULL) |[ (strcmp(mechanism, SAMPLE_MECH) != 0)) 

{ 
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return (NEXTPLUGIN); 

} 

rc = getEntryPassword( dn, &passwd); 
if (rc != LDAP_SUCCESS) 

{ 

slapi_send_ldap_result( pb, rc, NULL, NULL, 0, NULL ); 
return (STOP_PLUGIN_SEARCH); 

} 

/* Check if they gave the correct password */ 
if ((credentials->bv_val == NULL) |[ (passwd == NULL) | 
(strcmp(credentials->bv_val, passwd) != 0)) 

{ 

slapi_log_error( LDAP_MSG_LOW, SAMPLE_SUBSYSTEM, 

"Bind as %s failed\n", dn); 
rc = LDAP_INVALID_CREDENTIALS; 

} 

el se 

{ 

/* 

* Make a copy of the DN and authentication method and set them 

* in the pblock. The Server will use them for the connection. 

*/ 

connDn = slapi_ch_strdup(dn); 
if (connDn == NULL) 

{ 

sl api_1og_error( LDAP_MSG_LOW, SAMPLE_SUBSYSTEM, 

"Could not duplicate connection DN\n"); 
sl api_send_ldap_result( pb, LDAP_N0_MEM0RY, NULL, NULL, 0, NULL ); 
slapi_ch_free(passwd); 
return (STOP_PLUGIN_SEARCH); 

} 

/* 

* The authentication method string will look something like 

* "SASL SAMPLE_BIND" 

*/ 

aString = slapi_ch_malloc(strlen(SLAPD_AUTH_SASL) + 

Strien(SAMPLE_MECH) + 2); 

if (aString == NULL) 

{ 

slapi_log_error( LDAP_MSG_LOW, SAMPLE_SUBSYSTEM, 

"Could not duplicate authString\n"); 
slapi_ch_free(passwd); 
slapi_ch_free(connDn); 

slapi_send_ldap_result( pb, LDAP_N0_MEM0RY, NULL, NULL, 0, NULL ); 
return (STOP_PLUGIN_SEARCH); 

} 

sprintf(aString, "%s%s", SLAPD_AUTH_SASL, SAMPLE_MECH); 

/* Set the connection DN */ 

if (slapi_pblock_set( pb, SLAPI_CONN_DN, (void *) connDn) != 0) 

{ 

slapi_log_error( LDAP_MSG_L0W, SAMPLE_SUBSYSTEM, 

"Could not set SLAPI_C0NN_DN\n"); 
sl api_ch_free(passwd); 
slapi_ch_free(connDn); 
slapi_ch_free(aString); 

slapi_send_ldap_result( pb, LDAP_0PERATI0NS_ERR0R, NULL, NULL, 0, NULL ); 
return (STOP_PLUGIN_SEARCH); 

} 

/* Set the authentication type */ 

if (slapi_pblock_set( pb, SLAPI_CONN_AUTHTYPE, (void *) aString) != 0) 

{ 

sl api_1 og_error( LDAP_MSG_L0W, SAMPLE_SUBSYSTEM, 
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"Could not set SLAPI_CONN_AUTHTYPE\n"); 
slapi_ch_free(passwd); 

slapi_ch_free(connDn); 
slapi_ch_free(aString); 

slapi_send_ldap_result( pb, LDAP_OPERATIONS_ERROR, NULL, NULL, 0, NULL ); 
return (STOP_PLUGIN_SEARCH); 


rc = LDAP_SUCCESS; 


/* Send the result back to the dient */ 
slapi_send_ldap_result( pb, rc, NULL, NULL, 0, NULL ); 

/*Free the memory allocated by the plug-in */ 
slapi_ch_free(passwd); 
slapi_ch_free(connDn); 
slapi_ch_free(aString); 

return (STOP_PLUGIN_SEARCH); 

} 

To use the plug-in you must: 

1. Compile it. Use the following makefile to compile the plug-in: 

CC = gcc 

LINK = gcc -shared 
WARNINGS = -Wall -Werror 
LDAP_H0ME = /usr/ldap 

INCDIRS = -1 ${LDAP_H0ME}/include 
LIBDIRS = -L${LDAP_HOME}/lib 

CFLAGS = -g ${WARNINGS} ${INCDIRS} 

LINK_FLAGS = ${LIBDIRS} ${LIBS} 

PLUGIN = libsample.so 
OBJECTS = sample.o 

.PHONY: clean 

all: ${PLUGIN} 

.C.o: 

$ (CC) ${CFLAGS} -c -o $0 $< 

${PLUGIN}: ${OBJECTS} 

${LINK} -o $0 $< ${LINK_FLAGS} 

clean: 

${RM} ${PLUGIN} 

${RM} ${OBJ ECTS} 

2. Add the following information to the ibmslapd.conf file using the ldapmodify 
command: 

ldapmodify -D <adminDN> -\n<adminPkl> -\<filename> 
where <filename> contains: 

DN: cn=SchemaDB, cn=LDCF Backends, cn=IBM Directory, cn=Schemas, cn=Configuration 
changetype: modify 
add: ibm-slapdPlugin 

ibm-slapdPlugin: preoperation <path to plugin>/l ibsample.so samplelnit 

3. Restart the Server. If the plug-in was loaded, its initialization function writes a 
message to the ibmslapd.log file similar to the following: 

08/25/2003 01:28:50 PM SAMPLE: Hello from sample 
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4. Perform an LDAP Operation like the following: 

ldapsearch -m SAMPLE_BIND -D cn=bob,o=ibm,c=us -w hello -p 1234 
-b o=ibm,c=us objectclass=* 

The search succeeds if the entry cn=bob,o=ibm,c=us exists and has a user 
password attribute with the value hello. If the entry does not exist, an 
authentication denied error is returned. 
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Appendix D. Deprecated plug-in APIs 


Although the following APIs are still supported, their use is deprecated. Use of the 
newer replacement APIs is strongly encouraged. 


• slapi_dn_normalize. See 

"slapi dn normalize v3()" on page 20 


• slapi_dn_normalize_case. 

See 

"slapi dn normalize case v3()" on page 21 

• slapi_dn_ignore_case. See 

"slapi_dn_ignore_case_v3()" on page 22 
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Appendix E. Notices 


This information was developed for products and Services offered in the U.S.A. 
IBM might not öfter the products, Services, or features discussed in this document 
in other countries. Consult your local IBM representative for information on the 
products and Services currently available in your area. Any reference to an IBM 
product, program, or Service is not intended to state or imply that only that IBM 
product, program, or Service may be used. Any functionally equivalent product, 
program, or Service that does not infringe any IBM intellectual property right may 
be used instead. However, it is the user's responsibility to evaluate and verify the 
Operation of any non-IBM product, program, or Service. 

IBM may have patents or pending patent applications covering subject matter in 
this document. The furnishing of this document does not give you any license to 
these patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 
IBM Corporation 
North Castle Drive 
Armonk, NY 10504-1785 
U.S.A. 

For license inquiries regarding double-byte (DBCS) information, contact the IBM 
Intellectual Property Department in your country or send inquiries, in writing, to: 

IBM World Trade Asia Corporation Licensing 
2-31 Roppongi 3-chome, Minato-ku 
Tokyo 106, Japan 

The following paragraph does not apply to the United Kingdom or any other 
country where such provisions are inconsistent with local law: 

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS 
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER 
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS 
FOR A PARTICULAR PURPOSE. Some States do not allow disclaimer of express or 
implied warranties in certain transactions, therefore, this Statement may not apply 
to you. 

This information could include technical inaccuracies or typographical errors. 
Changes are periodically made to the information herein; these changes will be 
incorporated in new editions of the information. IBM may make improvements 
and/or changes in the product(s) and/or the program(s) described in this 
information at any time without notice. 

Any references in this information to non-IBM Web sites are provided for 
convenience only and do not in any mariner serve as an endorsement of those Web 
sites. The materials at those Web sites are not part of the materials for this IBM 
product and use of those Web sites is at your own risk. 

IBM may use or distribute any of the information you supply in any way it 
believes appropriate without incurring any Obligation to you. 
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Licensees of this program who wish to have information about it for the purpose 
of enabling: (i) the exchange of information between independently created 
programs and other programs (including this one) and (ii) the mutual use of the 
information which has been exchanged, should contact: 

IBM Corporation 

Department LZKS 

11400 Burnet Road 

Austin, TX 78758 

U.S.A. 

Such information may be available, subject to appropriate terms and conditions, 
including in some cases, payment of a fee. 

The licensed program described in this document and all licensed material 
available for it are provided by IBM under terms of the IBM Customer Agreement, 
IBM International Program License Agreement, or any equivalent agreement 
between us. 

Any performance data contained herein was determined in a controlled 
environment. Therefore, the results obtained in other operating environments may 
vary significantly. Some measurements may have been made on development-level 
Systems and there is no guarantee that these measurements will be the same on 
generally available Systems. Furthermore, some measurement may have been 
estimated through extrapolation. Actual results may vary. Users of this document 
should verify the applicable data for their specific environment. 

Information conceming non-IBM products was obtained from the suppliers of 
those products, their published announcements or other publicly available sources. 
IBM has not tested those products and cannot confirm the accuracy of 
performance, compatibility or any other claims related to non-IBM products. 
Questions on the capabilities of non-IBM products should be addressed to the 
suppliers of those products. 

All statements regarding IBM's future direction or intent are subject to change or 
withdrawal without notice, and represent goals and objectives only. 

All IBM prices shown are IBM's suggested retail prices, are current and are subject 
to change without notice. Dealer prices may vary. 

Trademarks 

The following terms are trademarks of International Business Machines 

Corporation in the United States, or other countries, or both: AIX, DB2, IBM, 
SecureWay, VisualAge. 

Windows, and Windows NT are registered trademarks of Microsoft Corporation. 

UNIX is a registered trademark of The Open Group in the United States and other 
countries. 

Other Company, product, and Service names may be trademarks or Service marks 
of others. 
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